An area of interest (AOI) is the geographic extent. It helps confine the unit of work to a geographic area, and helps to not only prioritize and define research and subsetting efforts, but improves reproducabilty across studies. ‘AOI` is an R package that lets users define an AOI through a common query and return a ’SpatialPolygon’ of that area.
Three parameters can be used to define a query: state, county, and clip_unit. This page illustrates how these parameters can be used define – and refine – a query.
An AOI can be defined by a state name or abbreviation:
CA = getAOI(state = 'CA')
A query can also be defined by multiple states provided as a vector:
WestCoast = getAOI(state = c("Oregon", "Washington", "CA"))Defining an AOI by county requires a state as well:
EP = getAOI(state = "CO", county = "El Paso")
Multiple counties can be queried if provided as a vector:
centralCoast = getAOI(state ="CA", county = c("Santa Barbara", "San Luis Obispo", "Ventura"))In HydroData a clip_unit is user defined region. Most commonly a bounding box or a supplied shapefile - both of which can be input as a clip_unit.
To define a bounding box clip_unit has four inputs given as a list:
Again, all clip_unit inputs must be provided as a list. It is also important to note that order DOES matter if each parameter is not explicitly assigned (eg h = 10). Examples for each input follow:
A Location is the first input in clip_unit list and can be given as a colloquial name (character string) or as a (lat/long) pair (numeric). Names are geocoded by the Google API via the dismo R package.
Here we query an AOI surrounding the Grand Canyon, using both the colloquial name, and the (lat/long) pair found with a Google search. Notice slightly different locations are generated:
GC_name = getAOI(clip_unit = list("grand canyon", 10, 10))
GC_lat_lon = getAOI(clip_unit = list(36.0544, -112.1401, 10, 10))Once a location is specified, the next two needed values are a bounding box height and width (in miles). The first entry defines height and the second width:
nwc.tall = getAOI(clip_unit = list("National Water Center, AL", 30, 10))
nwc.wide = getAOI(clip_unit = list("National Water Center, AL", 10, 30))With a location, height, and width defined the relationship of the box to the location is needed. By default (and in the previous examples) each bounding box was generated using the location as a centroid. You can change this by adding a final argument to the clip_unit list specifying where the location lies in reference to the box. Options include ‘center’, ‘lowerleft’, ‘lowerright’, ‘upperleft’, ‘upperright’:
ucsb.c = getAOI(clip_unit = list("UCSB", 10, 10, "center"))
ucsb.ul = getAOI(clip_unit = list("UCSB", 10, 10, "upperleft"))
ucsb.ur = getAOI(clip_unit = list("UCSB", 10, 10, "upperright"))
ucsb.ll = getAOI(clip_unit = list("UCSB", 10, 10, "lowerleft"))
ucsb.lr = getAOI(clip_unit = list("UCSB", 10, 10, "lowerright"))A user supplied shapefile can be used as input for the clip_unit parameter in lieu of a list() bounding box.
#Read in shapefile of all Los Angeles Communities
LA = rgdal::readOGR("shp/LA.shp", verbose = FALSE)
#Subset Santa Monica
SM = LA[LA$LABEL_CITY == 'Santa Monica',] %>% spTransform(aoiProj)
#Define AOI
AOI = getAOI(clip_unit = SM)One on the hardest aspects of defining an AOI is deciding on the query parameters (eg the location, width and height). To help with this the AOI package has a check function that can be used to define OR refine AOI queries.
If you have no idea about the constraints of your AOI you can run check() alone:
check()getAOI() call. check() function can also be chained to existing AOI call to immediately see the region being queried: getAOI(clip_unit = list("San Luis Obispo", 10, 10 )) %>% check()Now that you know how to define, view and refine an AOI, check out some packages and/or services that are using, or could use the AOI package for spatial subsetting calls:
HydroData
nwm
FlowlineFinder
FedData
nhdplusTools
Package development is supported with funds from the UCAR COMET program; the NOAA National Water Center; and the University of California, Santa Barbara (UCSB).